The cli-ux npm package provides a set of utilities for building command-line interfaces (CLIs). It offers features such as progress bars, spinners, prompts, and table formatting to enhance the user experience of CLI applications.
Progress Bar
This feature allows you to display a progress bar in the terminal. The code sample demonstrates how to create and update a progress bar that increments by 5% every 100 milliseconds until it reaches 100%.
const cli = require('cli-ux');
const progress = cli.progress({ format: 'progress [{bar}] {percentage}% | ETA: {eta}s' });
progress.start(100, 0);
let value = 0;
const interval = setInterval(() => {
value += 5;
progress.update(value);
if (value >= 100) {
clearInterval(interval);
progress.stop();
}
}, 100);Spinner
This feature provides a spinner to indicate ongoing processes. The code sample shows how to start a spinner with a message and stop it after 3 seconds with a 'done' message.
const cli = require('cli-ux');
cli.action.start('Processing');
setTimeout(() => {
cli.action.stop('done');
}, 3000);Prompt
This feature allows you to prompt the user for input. The code sample demonstrates how to ask the user for their name and then greet them with the provided input.
const cli = require('cli-ux');
(async () => {
const name = await cli.prompt('What is your name?');
console.log(`Hello, ${name}!`);
})();Table
This feature allows you to display data in a table format. The code sample shows how to create a table with two columns: 'name' and 'age', and display two rows of data.
const cli = require('cli-ux');
const data = [
{ name: 'John', age: 30 },
{ name: 'Jane', age: 25 }
];
cli.table(data, {
name: {
minWidth: 7
},
age: {
header: 'Age'
}
});Ora is a lightweight and elegant terminal spinner. It provides similar functionality to the spinner feature in cli-ux but focuses solely on spinners, offering more customization options and better performance.
Inquirer is a powerful library for creating interactive command-line prompts. It offers more advanced and flexible prompt types compared to cli-ux, making it a better choice for complex user interactions.
Blessed is a comprehensive library for building terminal interfaces. It provides a wide range of widgets, including tables, forms, and more, offering greater flexibility and customization than cli-ux.
Progress is a simple and flexible progress bar library for Node.js. It offers similar functionality to the progress bar feature in cli-ux but with a more minimalistic approach and fewer dependencies.
cli IO utilities
The following assumes you have installed cli-ux to your project with npm install cli-ux or yarn add cli-ux and have it required in your script (TypeScript example):
import cli from 'cli-ux'
cli.prompt('What is your name?')
JavaScript:
const {cli} = require('cli-ux')
cli.prompt('What is your name?')
Prompt for user input.
// just prompt for input
await cli.prompt('What is your name?')
// mask input after enter is pressed
await cli.prompt('What is your two-factor token?', {type: 'mask'})
// mask input on keypress (before enter is pressed)
await cli.prompt('What is your password?', {type: 'hide'})
// yes/no confirmation
await cli.confirm('Continue?')
// "press any key to continue"
await cli.anykey()
Create a hyperlink (if supported in the terminal)
await cli.url('sometext', 'https://google.com')
// shows sometext as a hyperlink in supported terminals
// shows https://google.com in unsupported terminals
Open a url in the browser
await cli.open('https://oclif.io')
Shows a spinner
// start the spinner
cli.action.start('starting a process')
// show on stdout instead of stderr
cli.action.start('starting a process', 'initializing', {stdout: true})
// stop the spinner
cli.action.stop() // shows 'starting a process... done'
cli.action.stop('custom message') // shows 'starting a process... custom message'
This degrades gracefully when not connected to a TTY. It queues up any writes to stdout/stderr so they are displayed above the spinner.
Shows an iterm annotation
cli.annotation('sometext', 'annotated with this text')
Waits for 1 second or given milliseconds
await cli.wait()
await cli.wait(3000)
Displays tabular data
cli.table(data, columns, options)
Where:
data: array of data objects to displaycolumns: Table.Columnsoptions: Table.Optionscli.table.flags() returns an object containing all the table flags to include in your command.
{
columns: Flags.string({exclusive: ['additional'], description: 'only show provided columns (comma-separated)'}),
sort: Flags.string({description: 'property to sort by (prepend '-' for descending)'}),
filter: Flags.string({description: 'filter property by partial string matching, ex: name=foo'}),
csv: Flags.boolean({exclusive: ['no-truncate'], description: 'output is csv format'}),
extended: Flags.boolean({char: 'x', description: 'show extra columns'}),
'no-truncate': Flags.boolean({exclusive: ['csv'], description: 'do not truncate output to fit screen'}),
'no-header': Flags.boolean({exclusive: ['csv'], description: 'hide table header from output'}),
}
Passing {only: ['columns']} or {except: ['columns']} as an argument into cli.table.flags() will allow/block those flags from the returned object.
Table.Columns defines the table columns and their display options.
const columns: Table.Columns = {
// where `.name` is a property of a data object
name: {}, // "Name" inferred as the column header
id: {
header: 'ID', // override column header
minWidth: '10', // column must display at this width or greater
extended: true, // only display this column when the --extended flag is present
get: row => `US-O1-${row.id}`, // custom getter for data row object
},
}
Table.Options defines the table options, most of which are the parsed flags from the user for display customization, all of which are optional.
const options: Table.Options = {
printLine: myLogger, // custom logger
columns: flags.columns,
sort: flags.sort,
filter: flags.filter,
csv: flags.csv,
extended: flags.extended,
'no-truncate': flags['no-truncate'],
'no-header': flags['no-header'],
}
Example class:
import {Command} from '@oclif/core'
import {cli} from 'cli-ux'
import axios from 'axios'
export default class Users extends Command {
static flags = {
...cli.table.flags()
}
async run() {
const {flags} = this.parse(Users)
const {data: users} = await axios.get('https://jsonplaceholder.typicode.com/users')
cli.table(users, {
name: {
minWidth: 7,
},
company: {
get: row => row.company && row.company.name
},
id: {
header: 'ID',
extended: true
}
}, {
printLine: this.log,
...flags, // parsed flags
})
}
}
Displays:
$ example-cli users
Name Company
Leanne Graham Romaguera-Crona
Ervin Howell Deckow-Crist
Clementine Bauch Romaguera-Jacobson
Patricia Lebsack Robel-Corkery
Chelsey Dietrich Keebler LLC
Mrs. Dennis Schulist Considine-Lockman
Kurtis Weissnat Johns Group
Nicholas Runolfsdottir V Abernathy Group
Glenna Reichert Yost and Sons
Clementina DuBuque Hoeger LLC
$ example-cli users --extended
Name Company ID
Leanne Graham Romaguera-Crona 1
Ervin Howell Deckow-Crist 2
Clementine Bauch Romaguera-Jacobson 3
Patricia Lebsack Robel-Corkery 4
Chelsey Dietrich Keebler LLC 5
Mrs. Dennis Schulist Considine-Lockman 6
Kurtis Weissnat Johns Group 7
Nicholas Runolfsdottir V Abernathy Group 8
Glenna Reichert Yost and Sons 9
Clementina DuBuque Hoeger LLC 10
$ example-cli users --columns=name
Name
Leanne Graham
Ervin Howell
Clementine Bauch
Patricia Lebsack
Chelsey Dietrich
Mrs. Dennis Schulist
Kurtis Weissnat
Nicholas Runolfsdottir V
Glenna Reichert
Clementina DuBuque
$ example-cli users --filter="company=Group"
Name Company
Kurtis Weissnat Johns Group
Nicholas Runolfsdottir V Abernathy Group
$ example-cli users --sort=company
Name Company
Nicholas Runolfsdottir V Abernathy Group
Mrs. Dennis Schulist Considine-Lockman
Ervin Howell Deckow-Crist
Clementina DuBuque Hoeger LLC
Kurtis Weissnat Johns Group
Chelsey Dietrich Keebler LLC
Patricia Lebsack Robel-Corkery
Leanne Graham Romaguera-Crona
Clementine Bauch Romaguera-Jacobson
Glenna Reichert Yost and Sons
Generate a tree and display it
let tree = cli.tree()
tree.insert('foo')
tree.insert('bar')
let subtree = cli.tree()
subtree.insert('qux')
tree.nodes.bar.insert('baz', subtree)
tree.display()
Outputs:
├─ foo
└─ bar
└─ baz
└─ qux
Generate a customizable progress bar and display it
const simpleBar = cli.progress()
simpleBar.start()
const customBar = cli.progress({
format: 'PROGRESS | {bar} | {value}/{total} Files',
barCompleteChar: '\u2588',
barIncompleteChar: '\u2591',
})
customBar.start()
Outputs:
bar1:
progress [=====================-------------------] 53% | ETA: 1s | 53/100
bar2:
PROGRESS | █████████████████████████████░░░░░░░░░░░ | 146/204 Files
To see a more detailed example, run
$ ts-node examples/progress.ts
This extends cli-progress see all of the options and customizations there, which can be passed in with the options object. Only the single bar variant of cli-progress is currently supported.
FAQs
cli IO utilities
The npm package cli-ux receives a total of 574,632 weekly downloads. As such, cli-ux popularity was classified as popular.
We found that cli-ux demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 7 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.